Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
Part Info Persistency
Parts can attach PartInfo data to their display frames. This data can be used to hold any information the part wants to associate with the display frame, and is stored persitently in the frame's storage unit. While the data is stored with the frame, the part editor is responsible for its 'ternalization, as the editor is the only entity that understands the structure and format of the part info.
Persistent Format
A frame's part info is stored in the frame's storage unit in the part info property. The standard name for this property is found in the constant kODPropPartInfo. Just as a part editor stores multiple representations of a part's contents in multiple values in the contents property, the editor should also store multiple representations of the part info which correspond to the representations of the contents. Some content formats may not have corresponding part info, especially interchange formats like JPEG or RTF. However, many editors will define formats with corresponding part info, and if your editor supports another editor's native format directly, it should also support the partInfo for that format.
The names of partInfo formats which are linked to a content format should be the same as the name of the content format, with the segment "PartInfo" appended to the end of the ISO name. For example, if your part content format was "SurfSoft:SurfText1.0" the part info should be "SurfSoft:SurfText1.0:PartInfo".
For a part which externalized representations for the formats "SurfText 1.0", "RTF", "ClarisWorks 3.0" and "ASCII", its display frames should have part info with formats "SurfSoft:SurfText1.0:PartInfo" and "Claris:ClarisWorks 3.0:PartInfo" (assuming the interchange formats have no associated part info).
'ternalizing Part Info
There are three calls in the Part API that deal with 'ternalization of part info:
• ReadPartInfo - internalizes the part info from persistent storage
• WritePartInfo - externalizes the part info into persistent storage
• ClonePartInfo - externalizes the part info as in WritePartInfo, but clones object references
In all of these calls, the frame passes a StorageUnitView which is focused to the frame's part info property, but not to any value within that property. Your part editor must get the view's storage unit, and focus it to value(s) in that property as necessary to read or write the formats it needs to.
When to Write
When externalizing a property of a persistent object, it is only necessary to write the data if it is the first time writing it, or if it has changed from the last time the object was externalized. As an optimization, you can keep an "isDirty" flag in a frame's part info, indicating whether it has changed from when it was internalized or last externalized. In WritePartInfo, if the flag is false, skip externalizing; if the flag is true, externalize the data and set the flag to false. Note that you must always externalize part info when cloning (in ClonePartInfo), as you are making a new copy.
Just as a part must mark the draft as dirty when its content needs to be externalized, it must also mark the draft dirty when part info needs to be externalized. The part should call draft->SetChangedFromPrev() when part info has changed and needs to be externalized. Note that changes to part info in a non-persistent frame should not mark the draft dirty.
Sample Code
This code 'ternalizes a simple part info structure. The only value in it is an RGB color describing the background color of the frame. The forDebuggingRGBColor intermediate value makes debugging easier.
